.TH std::insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::insert_iterator \- std::insert_iterator

.SH Synopsis
   Defined in header <iterator>
   template< class Container >

   class insert_iterator : public                                         \fI(until C++17)\fP
   std::iterator<std::output_iterator_tag,

                                                void, void, void, void>
   template< class Container >                                            \fI(since C++17)\fP
   class insert_iterator;

   std::insert_iterator is a LegacyOutputIterator that inserts elements into a
   container for which it was constructed, at the position pointed to by the supplied
   iterator. The container's insert() member function is called whenever the iterator
   (whether dereferenced or not) is assigned to. Incrementing the std::insert_iterator
   is a no-op.

.SH Member types

   Member type       Definition
   iterator_category std::output_iterator_tag
   value_type        void
   difference_type   void           \fI(until C++20)\fP
                     std::ptrdiff_t \fI(since C++20)\fP
   pointer           void
   reference         void
   container_type    Container

   Member types iterator_category, value_type, difference_type, pointer
   and reference are required to be obtained by inheriting from           \fI(until C++17)\fP
   std::iterator<std::output_iterator_tag, void, void, void, void>.

.SH Member functions

   constructor     constructs a new insert_iterator
                   \fI(public member function)\fP
   operator=       inserts an object into the associated container
                   \fI(public member function)\fP
   operator*       no-op
                   \fI(public member function)\fP
   operator++      no-op
   operator++(int) \fI(public member function)\fP

.SH Member objects

   Member name                         Definition
   container \fI(protected member object) a pointer o\fPf type Container*
                                       an iterator of type
                                       Container::iterator
   iter \fI(protected member object)      \\fPfI(until C++20)\fP
                                       ranges::iterator_t<Container>
                                       \fI(since C++20)\fP

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <iterator>
 #include <list>
 #include <vector>

 int main()
 {
     std::vector<int> v{1, 2, 3, 4, 5};
     std::list<int> l{-1, -2, -3};
     std::copy(v.begin(), v.end(), // may be simplified with std::inserter
               std::insert_iterator<std::list<int>>(l, std::next(l.begin())));
     for (int n : l)
         std::cout << n << ' ';
     std::cout << '\\n';
 }

.SH Output:

 -1 1 2 3 4 5 -2 -3

.SH See also

                         creates a std::insert_iterator of type inferred from the
   inserter              argument
                         \fI(function template)\fP
   back_insert_iterator  iterator adaptor for insertion at the end of a container
                         \fI(class template)\fP
   front_insert_iterator iterator adaptor for insertion at the front of a container
                         \fI(class template)\fP
